accessible: Add some docs

Explain briefly how a11y works for entry wrappers
(since I won't remember a few months from now).

diff --git a/gtk/gtkaccessible.c b/gtk/gtkaccessible.c
index 6215e032d890509de7746668be5fd9b64c25ddc5..1f3e2a3209d0fd2ecc539516c6376041c74dc74f 100644 (file)
--- a/gtk/gtkaccessible.c
+++ b/gtk/gtkaccessible.c
@@ -638,6 +638,20 @@ gtk_accessible_role_to_name (GtkAccessibleRole  role,
   return role_names[role];
 }
 
+/*<private>
+ * gtk_accessible_platform_changed:
+ * @self: a #GtkAccessible
+ * @change: the platform state change to report
+ *
+ * ARIA discriminates between author-controlled states
+ * and 'platform' states, which are not. This function
+ * can be used by widgets to inform ATs that a platform
+ * state, such as focus, has changed.
+ *
+ * Note that the state itself is not included in this API.
+ * AT backends should use gtk_accessible_get_platform_state()
+ * to obtain the actual state.
+ */
 void
 gtk_accessible_platform_changed (GtkAccessible               *self,
                                  GtkAccessiblePlatformChange  change)
@@ -660,6 +674,21 @@ gtk_accessible_platform_changed (GtkAccessible               *self,
   gtk_at_context_update (context);
 }
 
+/*<private>
+ * gtk_accessible_get_platform_state:
+ * @self: a #GtkAccessible
+ * @state: platform state to query
+ *
+ * Query a platform state, such as focus.
+ *
+ * See gtk_accessible_platform_changed().
+ *
+ * This functionality can be overridden by #GtkAccessible
+ * implementations, e.g. to get platform state from an ignored
+ * child widget, as is the case for #GtkText wrappers.
+ *
+ * Returns: the value of @state for the accessible
+ */
 gboolean
 gtk_accessible_get_platform_state (GtkAccessible              *self,
                                    GtkAccessiblePlatformState  state)
@@ -667,6 +696,19 @@ gtk_accessible_get_platform_state (GtkAccessible              *self,
   return GTK_ACCESSIBLE_GET_IFACE (self)->get_platform_state (self, state);
 }
 
+/*<private>
+ * gtk_accessible_should_present:
+ * @self: a #GtkAccessible
+ *
+ * Returns whether this accessible should be represented to ATs.
+ *
+ * By default, hidden widgets are are among these, but there can
+ * be other reasons to return %FALSE, e.g. for widgets that are
+ * purely presentations, or for widgets whose functionality is
+ * represented elsewhere, as is the case for #GtkText widgets.
+ *
+ * Returns: %TRUE if the widget should be represented
+ */
 gboolean
 gtk_accessible_should_present (GtkAccessible *self)
 {

diff --git a/gtk/gtkentry.c b/gtk/gtkentry.c
index 68495f062af9200b4857d6ab49828cfcff7857b9..532d3896fe740bf43455f17f2cc9ea7a29b57bdd 100644 (file)
--- a/gtk/gtkentry.c
+++ b/gtk/gtkentry.c
@@ -334,6 +334,12 @@ G_DEFINE_TYPE_WITH_CODE (GtkEntry, gtk_entry, GTK_TYPE_WIDGET,
                          G_IMPLEMENT_INTERFACE (GTK_TYPE_CELL_EDITABLE,
                                                 gtk_entry_cell_editable_init))
 
+/* Implement the GtkAccessible interface, in order to obtain focus
+ * state from the #GtkText widget that we are wrapping. The GtkText
+ * widget is ignored for accessibility purposes (it has role NONE),
+ * and any a11y text functionality is implemented for GtkEntry and
+ * similar wrappers (GtkPasswordEntry, GtkSpinButton, etc).
+ */
 static gboolean
 gtk_entry_accessible_get_platform_state (GtkAccessible              *self,
                                          GtkAccessiblePlatformState  state)